﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Untitled Document</title>
<style type="text/css">

body {
	font-family: Geneva, Arial, Helvetica, sans-serif;
}

</style>
</head>

<body>
<h2><a name="Userprefs_Ref"></a>User Preferences </h2>
              <p>Some gadgets need to give users a way of supplying user-specific
                  information. For example, a weather gadget might require
                  users to provide their postal codes. The user preferences
                  (<code>&lt;UserPref&gt;</code>) section
                  in the XML file describes the user input fields that
                  are turned into user interface controls when the gadget
                  runs. </p>
              <p>The following table lists the <code>&lt;UserPref&gt;</code> attributes:</p>

              <table>
                  <tbody><tr>
                      <th>Attribute</th>
                      <th>Description</th>
                  </tr>
                  <tr>
                      <td><code>name </code></td>

                      <td>Required "symbolic" name of the user
                          preference; displayed to the user during editing
                          if no <code>display_name</code> is defined.
                          Must contain only letters, number and underscores,
                          i.e. the regular expression ^[a-zA-Z0-9_]+$.
                          Must be unique.</td>
                  </tr>
                  <tr>
                      <td><code>display_name </code></td>

                      <td>Optional string to display alongside the user
                          preferences in the edit window. Must be unique. </td>

                  </tr>
                  <tr>
                      <td><code>urlparam </code></td>
                      <td>Optional string to pass as the parameter name
                          for content <code>type="url"</code>.</td>
                  </tr>

                  <tr>

                      <td><code>datatype </code></td>
                      <td>Optional string that indicates the data type
                          of this attribute. Can be <code>string</code>, <code>bool</code>, <code><a href="#Enums">enum</a></code>, <code>hidden</code> (a
                          string that is not visible or user editable), or <code><a href="fundamentals.html#list">list</a></code> (dynamic
                          array generated from user input). The default is <code>string</code>.                          </td>

                  </tr>
                  <tr>
                      <td><code>required</code> </td>
                      <td>Optional boolean argument (<code>true</code> or <code>false</code>)
                          indicating whether this user preference is required.
                          The default is <code>false</code>. </td>

                  </tr>
                  <tr>
                      <td><code>default_value </code></td>
                      <td>Optional string that indicates a user preference's
                          default value.</td>
                  </tr>
              </tbody></table>
              <p>User preferences can be accessed from your gadget using
                  the user preferences <a href="/apis/gadgets/docs/reference/">JavaScript API</a>,
                  for example:</p>

              
              <pre>&lt;script type="text/javascript"&gt;
   var prefs = new _IG_Prefs();
   var someStringPref = prefs.getString("StringPrefName");
   var someIntPref = prefs.getInt("IntPrefName");
   var someBoolPref = prefs.getBool("BoolPrefName");
&lt;/script&gt;</pre>
              
              
</body>
</html>
